Description

In the Pickup.Create parameter set, both the Shipment and the Batch parameters are marked as "optional". In a vacuum, yes, neither is required on any given API call. However, at least one of them is required for every API call. With our current solution, since both are "optional", it is possible for an end-user to build a parameter set with both excluded, which will ultimately result in a bad request being sent to the API and a resultant error.

This PR introduces the concept of a dependency attribute/decorator which can denote the relationship between multiple parameters in a given parameter set. Specifically, the decorator denotes any other parameters that are dependent on the marked parameter, and what the condition is. For the Shipment and Batch example, both parameters are marked with this new attribute, which indicates that, e.g. if Shipment is set, Batch must not be set, and if Shipment is not set, Batch must be set (and vice versa from the Batch perspective; if Batch is set, Shipment must not be set, and if Batch is not set, Shipment must be set)

[TopLevelRequestParameter(Necessity.Optional, "pickup", "shipment")]
[TopLevelRequestParameterDependents(IndependentStatus.IfSet, DependentStatus.MustNotBeSet, "Batch")]
[TopLevelRequestParameterDependents(IndependentStatus.IfNotSet, DependentStatus.MustBeSet, "Batch")]
public IShipmentParameter? Shipment { get; set; }

These relationships (which can be extended to account for multiple dependent parameters, not just pairs, as well as enforced as one-way relationships) are searched for and evaluated if found during the serialization process. If the condition between parameters in a relationship fails, a local exception is thrown indicating that the pair is invalid. This is done pre-flight, meaning any invalid pair will not make it to the API as it will fail local validation first.

This PR:

• Adds new dependency attributes for both top-level and nested parameters
• Adds a new InvalidParameterPair exception type
• Implements dependency evaluation during parameter serialization
• Denotes dependency relationship between Shipment and Batch parameters in the Pickup.Create parameter set, so that one (but not both nor neither) must be provided for each set.

Testing

• New unit test to check parameter interdependency evaluation when only one (but not both nor neither) should be set
• New unit test to check parameter interdependency evaluation when both or neither (but not just one) should be set
• New unit test for InvalidParameterPair construction and message

Pull Request Type

Please select the option(s) that are relevant to this PR.

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Improvement (fixing a typo, updating readme, renaming a variable name, etc)